<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Executor requirements</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../../index.html" title="Asio">
<link rel="up" href="../reference.html" title="Reference">
<link rel="prev" href="ExecutionContext.html" title="Execution context requirements">
<link rel="next" href="GettableSerialPortOption.html" title="Gettable serial port option requirements">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="asio C++ library" width="250" height="60" src="../../asio.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="ExecutionContext.html"><img src="../../prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../home.png" alt="Home"></a><a accesskey="n" href="GettableSerialPortOption.html"><img src="../../next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="asio.reference.Executor1"></a><a class="link" href="Executor1.html" title="Executor requirements">Executor requirements</a>
</h3></div></div></div>
<p>
        The library describes a standard set of requirements for <span class="emphasis"><em>executors</em></span>.
        A type meeting the <code class="computeroutput">Executor</code> requirements embodies a set of rules
        for determining how submitted function objects are to be executed.
      </p>
<p>
        A type <code class="computeroutput">X</code> meets the <code class="computeroutput">Executor</code> requirements if it
        satisfies the requirements of <code class="computeroutput">CopyConstructible</code> (C++Std [copyconstructible])
        and <code class="computeroutput">Destructible</code> (C++Std [destructible]), as well as the additional
        requirements listed below.
      </p>
<p>
        No constructor, comparison operator, copy operation, move operation, swap
        operation, or member functions <code class="computeroutput">context</code>, <code class="computeroutput">on_work_started</code>,
        and <code class="computeroutput">on_work_finished</code> on these types shall exit via an exception.
      </p>
<p>
        The executor copy constructor, comparison operators, and other member functions
        defined in these requirements shall not introduce data races as a result
        of concurrent calls to those functions from different threads.
      </p>
<p>
        Let <code class="computeroutput">ctx</code> be the execution context returned by the executor's
        <code class="computeroutput">context()</code> member function. An executor becomes <span class="emphasis"><em>invalid</em></span>
        when the first call to <code class="computeroutput">ctx.shutdown()</code> returns. The effect of
        calling <code class="computeroutput">on_work_started</code>, <code class="computeroutput">on_work_finished</code>, <code class="computeroutput">dispatch</code>,
        <code class="computeroutput">post</code>, or <code class="computeroutput">defer</code> on an invalid executor is undefined.
        [<span class="emphasis"><em>Note:</em></span> The copy constructor, comparison operators, and
        <code class="computeroutput">context()</code> member function continue to remain valid until <code class="computeroutput">ctx</code>
        is destroyed. &#8212;<span class="emphasis"><em>end note</em></span>]
      </p>
<p>
        In the table below, <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code> denote (possibly
        const) values of type <code class="computeroutput">X</code>, <code class="computeroutput">mx1</code> denotes an xvalue
        of type <code class="computeroutput">X</code>, <code class="computeroutput">f</code> denotes a <code class="computeroutput">MoveConstructible</code>
        (C++Std [moveconstructible]) function object callable with zero arguments,
        <code class="computeroutput">a</code> denotes a (possibly const) value of type <code class="computeroutput">A</code> meeting
        the <code class="computeroutput">Allocator</code> requirements (C++Std [allocator.requirements]),
        and <code class="computeroutput">u</code> denotes an identifier.
      </p>
<div class="table">
<a name="asio.reference.Executor1.t0"></a><p class="title"><b>Table&#160;14.&#160;Executor requirements</b></p>
<div class="table-contents"><table class="table" summary="Executor requirements">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  expression
                </p>
              </th>
<th>
                <p>
                  type
                </p>
              </th>
<th>
                <p>
                  assertion/note<br> pre/post-conditions
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput">X u(x1);</code>
                </p>
              </td>
<td>
              </td>
<td>
                <p>
                  Shall not exit via an exception.<br> <br> post: <code class="computeroutput">u ==
                  x1</code> and <code class="computeroutput">std::addressof(u.context()) == std::addressof(x1.context()).</code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput">X u(mx1);</code>
                </p>
              </td>
<td>
              </td>
<td>
                <p>
                  Shall not exit via an exception.<br> <br> post: <code class="computeroutput">u</code>
                  equals the prior value of <code class="computeroutput">mx1</code> and <code class="computeroutput">std::addressof(u.context())</code>
                  equals the prior value of <code class="computeroutput">std::addressof(mx1.context())</code>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput">x1 == x2</code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput">bool</code>
                </p>
              </td>
<td>
                <p>
                  Returns <code class="computeroutput">true</code> only if <code class="computeroutput">x1</code> and <code class="computeroutput">x2</code>
                  can be interchanged with identical effects in any of the expressions
                  defined in these type requirements. [<span class="emphasis"><em>Note:</em></span>
                  Returning <code class="computeroutput">false</code> does not necessarily imply that the
                  effects are not identical. &#8212;<span class="emphasis"><em>end note</em></span>] <br>
                  <br> <code class="computeroutput">operator==</code> shall be reflexive, symmetric, and
                  transitive, and shall not exit via an exception.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput">x1 != x2</code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput">bool</code>
                </p>
              </td>
<td>
                <p>
                  Same as <code class="computeroutput">!(x1 == x2)</code>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput">x1.context()</code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput">execution_context&amp;</code>, or <code class="computeroutput">E&amp;</code> where
                  <code class="computeroutput">E</code> is a type that satifisfies the <a class="link" href="ExecutionContext.html" title="Execution context requirements"><code class="computeroutput">ExecutionContext</code></a>
                  requirements.
                </p>
              </td>
<td>
                <p>
                  Shall not exit via an exception.<br> <br> The comparison operators
                  and member functions defined in these requirements shall not alter
                  the reference returned by this function.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput">x1.on_work_started()</code>
                </p>
              </td>
<td>
              </td>
<td>
                <p>
                  Shall not exit via an exception.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput">x1.on_work_finished()</code>
                </p>
              </td>
<td>
              </td>
<td>
                <p>
                  Shall not exit via an exception.<br> <br> Precondition: A preceding
                  call <code class="computeroutput">x2.on_work_started()</code> where <code class="computeroutput">x1 == x2</code>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput">x1.dispatch(std::move(f),a)</code>
                </p>
              </td>
<td>
              </td>
<td>
                <p>
                  Effects: Creates an object <code class="computeroutput">f1</code> initialized with <code class="literal"><span class="emphasis"><em>DECAY_COPY</em></span></code><code class="computeroutput">(forward&lt;Func&gt;(f))</code>
                  (C++Std [thread.decaycopy]) in the current thread of execution
                  . Calls <code class="computeroutput">f1()</code> at most once. The executor may block
                  forward progress of the caller until <code class="computeroutput">f1()</code> finishes
                  execution.<br> <br> Executor implementations should use the
                  supplied allocator to allocate any memory required to store the
                  function object. Prior to invoking the function object, the executor
                  shall deallocate any memory allocated. [<span class="emphasis"><em>Note:</em></span>
                  Executors defined in this Technical Specification always use the
                  supplied allocator unless otherwise specified. &#8212;<span class="emphasis"><em>end note</em></span>]
                  <br> <br> Synchronization: The invocation of <code class="computeroutput">dispatch</code>
                  synchronizes with (C++Std [intro.multithread]) the invocation of
                  <code class="computeroutput">f1</code>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput">x1.post(std::move(f),a)</code><br> <code class="computeroutput">x1.defer(std::move(f),a)</code>
                </p>
              </td>
<td>
              </td>
<td>
                <p>
                  Effects: Creates an object <code class="computeroutput">f1</code> initialized with <code class="literal"><span class="emphasis"><em>DECAY_COPY</em></span></code><code class="computeroutput">(forward&lt;Func&gt;(f))</code>
                  in the current thread of execution. Calls <code class="computeroutput">f1()</code> at
                  most once. The executor shall not block forward progress of the
                  caller pending completion of <code class="computeroutput">f1()</code>.<br> <br> Executor
                  implementations should use the supplied allocator to allocate any
                  memory required to store the function object. Prior to invoking
                  the function object, the executor shall deallocate any memory allocated.
                  [<span class="emphasis"><em>Note:</em></span> Executors defined in this Technical
                  Specification always use the supplied allocator unless otherwise
                  specified. &#8212;<span class="emphasis"><em>end note</em></span>] <br> <br> Synchronization:
                  The invocation of <code class="computeroutput">post</code> or <code class="computeroutput">defer</code> synchronizes
                  with (C++Std [intro.multithread]) the invocation of <code class="computeroutput">f1</code>.<br>
                  <br> [<span class="emphasis"><em>Note:</em></span> Although the requirements placed
                  on <code class="computeroutput">defer</code> are identical to <code class="computeroutput">post</code>, the use
                  of <code class="computeroutput">post</code> conveys a preference that the caller <span class="emphasis"><em>does
                  not</em></span> block the first step of <code class="literal">f1</code>'s
                  progress, whereas <code class="computeroutput">defer</code> conveys a preference that
                  the caller <span class="emphasis"><em>does</em></span> block the first step of <code class="literal">f1</code>.
                  One use of <code class="computeroutput">defer</code> is to convey the intention of the
                  caller that <code class="literal">f1</code> is a continuation of the current
                  call context. The executor may use this information to optimize
                  or otherwise adjust the way in which <code class="computeroutput">f1</code> is invoked.
                  &#8212;<span class="emphasis"><em>end note</em></span>]
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003-2018 Christopher M. Kohlhoff<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="ExecutionContext.html"><img src="../../prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../home.png" alt="Home"></a><a accesskey="n" href="GettableSerialPortOption.html"><img src="../../next.png" alt="Next"></a>
</div>
</body>
</html>
